{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "2ae44fa2-2ef0-4204-b9bb-b6051dfefd7c",
   "metadata": {},
   "source": [
    "# Size And Layout Options\n",
    "\n",
    "Customization options for plot sizes and overall layout, including responsive mode and widget location:\n",
    "\n",
    "```{eval-rst}\n",
    ".. plotting-options-table:: Size And Layout Options\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c20d146d-c67f-40be-b505-edadc4e94bd7",
   "metadata": {},
   "source": [
    "(option-aspect)=\n",
    "## `aspect`\n",
    "\n",
    "The `aspect` option controls the **frame** shape—that is, the rectangular drawing area that contains only the plotted data (excluding axes, labels, legends, and margins)—by setting the ratio of its width to its height. By default (`aspect=None`), HoloViews does not enforce any new ratio: it simply uses whatever `frame_height` and `frame_width` you’ve provided or falls back to its built-in defaults of 300 × 700 px if neither is set.  \n",
    "\n",
    "Use:\n",
    "\n",
    "- `'square'`: Forces a square frame.  \n",
    "  - If you set only `frame_width`, the height will be made equal to it.  \n",
    "  - If you set only `frame_height`, the width will be matched to it.  \n",
    "  - If you set both, the aspect value will be ignored with a warning displayed.\n",
    "\n",
    "- `'equal'`: Ensures the frame maintains the default height to width ratios (300:700). \n",
    "  - If you specify `frame_width` but omit `frame_height`, the height is re-computed to match the original ratios.  \n",
    "  - If you specify `frame_height` but omit `frame_width`, the width is re-computed to match the original ratios.  \n",
    "  - If you explicitly set both `frame_width` and `frame_height`, those values are respected and the aspect value ignored.\n",
    "\n",
    "- A float, e.g. `2.0`: Directly sets the width : height ratio (so `aspect=2.0` makes it twice as wide as it is tall).\n",
    "\n",
    "If you need to control the **data-unit** scaling (so that one y-unit equals one x-unit), use the [`data_aspect`](option-data_aspect) option instead.  \n",
    "\n",
    "Keeping `aspect` and `data_aspect` distinct lets you manage both your plot’s **pixel proportions** and your **data-unit proportions** independently.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fe824752-06d2-43f3-aa49-770a118c2222",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.penguins(\"pandas\")\n",
    "\n",
    "opts = dict(x='bill_length_mm', y='bill_depth_mm', frame_width=200)\n",
    "(\n",
    "      df.hvplot.scatter(aspect=None, title=\"Default aspect\", **opts)\n",
    "    + df.hvplot.scatter(aspect=0.6, title=\"3:5 ratio\", **opts)\n",
    "    + df.hvplot.scatter(aspect='square', title=\"Square plot (1:1 ratio)\", **opts)\n",
    "    + df.hvplot.scatter(aspect='equal', title=\"Re-computed frame_height\", **opts)\n",
    ").cols(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "24837128-7483-4a70-9fa0-011dc1d73606",
   "metadata": {},
   "source": [
    ":::{seealso}\n",
    "[`frame_width/frame_height`](option-frame_width__frame_height)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "de030cee-46a2-4d8d-b12a-e685bd616e27",
   "metadata": {},
   "source": [
    "(option-data_aspect)=\n",
    "## `data_aspect`\n",
    "\n",
    "The `data_aspect` option sets the scaling between axis units, i.e., the ratio of the number of y-units per x-unit.\n",
    "This is particularly useful for geographic or image data where you want equal distances on both axes (e.g., a degree of latitude and longitude should appear equal).\n",
    "\n",
    "Unlike [`aspect`](option-aspect) which controls **plot shape**, `data_aspect` affects the **visual scaling of the data itself**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "eb20eb44-6216-4a94-94e7-1c50c2755eb0",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.xarray  # noqa\n",
    "\n",
    "ds = hvplot.sampledata.air_temperature(\"xarray\").sel(time=\"2014-02-25 12:00\")\n",
    "\n",
    "ds.hvplot.image(data_aspect=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c99dceda-b76f-450a-90ac-06735a1b001c",
   "metadata": {},
   "source": [
    "(option-frame_width__frame_height)=\n",
    "## `frame_width / frame_height`\n",
    "\n",
    "The `frame_width` and `frame_height` options determine the width and height of the data area within the plot. They define the size of the plot’s core region (excluding axes, legends, and margins), allowing precise control over how the data is displayed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "de201f6b-0f7c-431a-8141-b86828068548",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.penguins(\"pandas\")\n",
    "\n",
    "df.hvplot.scatter(\n",
    "    \"bill_length_mm\", \"bill_depth_mm\", by=\"species\",\n",
    "    frame_width=300, frame_height=200\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e7b0802b-ca6a-4da9-be28-93351e142475",
   "metadata": {},
   "source": [
    "Setting `width` and `height` to the same values, notice how the plot below ends up much smaller than the one above, as `width` and `height` affect the whole plot area."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7254e255-2232-4f0b-a9be-d7520aed2821",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.penguins(\"pandas\")\n",
    "\n",
    "df.hvplot.scatter(\n",
    "    \"bill_length_mm\", \"bill_depth_mm\", by=\"species\",\n",
    "    width=300, height=200\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16e0b4c9-1648-4087-82b9-0f1e3b064cd0",
   "metadata": {},
   "source": [
    "(option-max_width__max_height)=\n",
    "## `max_width / max_height`\n",
    "\n",
    "The `max_width` and `max_height` options set the maximum allowed dimensions for the plot. These options come into play in responsive or dynamic layouts to ensure that the plot does not grow beyond the specified limits when the browser window is resized."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a6fbe571-c429-496f-809d-9f304f4773f5",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.xarray  # noqa\n",
    "\n",
    "df = hvplot.sampledata.air_temperature(\"xarray\").sel(time=\"2014-02-25 12:00\")\n",
    "\n",
    "df.hvplot.image(max_width=600, max_height=400, height=400, responsive=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6848e006-ff12-4ccb-b9bf-85f9b8a02615",
   "metadata": {},
   "source": [
    "By setting `max_width=600`, the plot cannot extend beyond 600 pixel units horizontally no matter the screen size the plot is being viewed in.\n",
    "\n",
    ":::{tip}\n",
    "Try to view this plot on the largest screen you can find and see if the plot width extends beyond 600 pixel units.\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6795d04b-e475-4b59-98d5-8afc7da4e6f0",
   "metadata": {},
   "source": [
    ":::{seealso}\n",
    "- [`min_width / min_height`](option-min_width__min_height)\n",
    "- [`responsive`](option-responsive)\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8b39ac83-1031-4e11-9d86-ee42c35b4156",
   "metadata": {},
   "source": [
    "(option-min_width__min_height)=\n",
    "## `min_width / min_height`\n",
    "\n",
    "Similar to [`max_width` and `max_height`](option-max_width__max_height), these options define the minimum width and height for the plot. They ensure that the plot will not shrink below the specified dimensions in responsive layouts, helping maintain legibility even on smaller screens."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e3e5dde3-1b2c-42e2-96f1-23e6c1d212ad",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.xarray  # noqa\n",
    "\n",
    "df = hvplot.sampledata.air_temperature(\"xarray\").sel(time=\"2014-02-25 12:00\")\n",
    "\n",
    "df.hvplot.image(min_width=300, min_height=200, height=400, responsive=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5b9faf80-dc9b-4dd6-ae8d-f73518cfc697",
   "metadata": {},
   "source": [
    ":::{tip}\n",
    "View this plot using your phone screen to see how the plot resizes\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9c58154b-e379-4e7f-9c00-db60aa001629",
   "metadata": {},
   "source": [
    ":::{seealso}\n",
    "- [`max_width / max_height`](option-max_width__max_height)\n",
    "- [`responsive`](option-responsive)\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e5540910-2fbf-4d82-9528-616cb9a11a29",
   "metadata": {},
   "source": [
    "(option-height)=\n",
    "## `height`\n",
    "\n",
    "The `height` and `width` option sets the overall height and width of the plot in pixels. By default, this is usually set to 300 and 700 pixels respectively. This dimension includes all components of the plot such as titles, labels, and margins."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "515f003d-090c-4dde-b3de-7d1ddbc1f979",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.xarray  # noqa\n",
    "\n",
    "df = hvplot.sampledata.air_temperature(\"xarray\").sel(time=\"2014-02-25 12:00\")\n",
    "\n",
    "df.hvplot.image(height=300, width=600)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "71fda055-de30-4d01-b2b3-3c0887403f7e",
   "metadata": {},
   "source": [
    "(option-width)=\n",
    "## `width`\n",
    "\n",
    "See [`height`](option-height) option above."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "52616cd0-101a-4a7f-89d0-0d9e2f93370a",
   "metadata": {},
   "source": [
    "(option-padding)=\n",
    "## `padding`\n",
    "\n",
    "The `padding` option expands the plot’s automatically computed axis limits by a given fraction. When hvPlot determines the x and y ranges based on your data, it finds the minimum and maximum values needed to display all points. With padding applied, these ranges are extended by the specified fraction so that data points near the edges have more space. The padding value can be given as a single number for uniform padding, a tuple to specify different padding for the x- and y-axes, or even a nested tuple to set distinct padding for the upper and lower bounds of each axis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4371a176-ef4e-483c-a7e3-5cfb77c5d51f",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = pd.DataFrame({'x': [0, 1, 0, -1], 'y': [-1, 0, 1, 0]})\n",
    "\n",
    "# Add 20% extra space around the auto-determined axis ranges\n",
    "df.hvplot.scatter(x='x', y='y', padding=0.2, height=200)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "091b16fc-608a-46ac-8c55-154bf9989871",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = pd.DataFrame({'x': [0, 1, 0, -1], 'y': [-1, 0, 1, 0]})\n",
    "\n",
    "# Add 20% on the x-axis and 5% on the y-axis\n",
    "df.hvplot.scatter(x='x', y='y', padding=(0.2, 0.05), height=200)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c900e07-2108-4741-859b-12309b41d03a",
   "metadata": {},
   "source": [
    "(option-responsive)=\n",
    "## `responsive`\n",
    "\n",
    "When set to `True`, the responsive option allows the plot to automatically adjust its size based on the browser window. Note that responsive mode works only if at least one dimension (`width` or `height`) is left undefined; otherwise, the plot size remains fixed. This option is not supported by the static plotting backend Matplotlib."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "846fdde4-9983-4101-a112-b184fe3f4dc0",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.penguins(\"pandas\")\n",
    "\n",
    "df.hvplot.scatter(\n",
    "    x='bill_length_mm', y='bill_depth_mm', by='species',\n",
    "    height=300, responsive=True\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ebba9610-b631-47dd-9724-b77dde317412",
   "metadata": {},
   "source": [
    "(option-widget_location)=\n",
    "## `widget_location`\n",
    "\n",
    "Control where widgets appear. Valid values are `'right'` (default), `'left'`, `'bottom'`, `'right'`, `'top'`, `'top_left'`, `'top_right'`, `'bottom_left'`, `'bottom_right'`, `'left_top'`, `'left_bottom'`, `'right_top'`, `'right_bottom'`.\n",
    "\n",
    ":::{important}\n",
    "When this option is set the object returned is no longer a HoloViews object but a Panel layout. In the future we intend to address that, follow [this issue](https://github.com/holoviz/holoviews/issues/6590) for more information.\n",
    ":::"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ea2a8936-5837-474c-a9cc-b0da34093b97",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.penguins(\"pandas\")\n",
    "\n",
    "df.hvplot.scatter(\n",
    "    x='bill_length_mm', y='bill_depth_mm', frame_width=250,\n",
    "    groupby='species', title='Default widget location'\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "699aa6a8-2a83-4d46-905f-b68fe2369e00",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.penguins(\"pandas\")\n",
    "\n",
    "df.hvplot.scatter(\n",
    "    x='bill_length_mm', y='bill_depth_mm', frame_width=250,\n",
    "    groupby='species', title='Widget on the top',\n",
    "    widget_location='top',\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9a7924e9-b9f9-4238-a4cf-e8449cedb8cb",
   "metadata": {},
   "source": [
    ":::{seealso}\n",
    "- [`min_width / min_height`](option-min_width__min_height)\n",
    "- [`max_width / max_height`](option-max_width__max_height)\n",
    ":::"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
